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Foreword 



This Technical Specification has been produced by the 3' Generation Partnership Project (3GPP). 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 
where: 

X the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



The present document is part 1 of a multi-part TS covering the 3' Generation Partnership Project: Technical 
Specification Group Core Network and Terminals; Open Service Access (OSA); Application Programming Interface 
(API), as identified below. The API specification (3GPP TS 29.198) is structured in the following Parts: 



Part 1: 

Part 2: 
Part 3: 
Part 4: 



Parts 
Part 6 
Part? 
Parts 
Part 9 
Part 10 
Part 11 
Part 12 
Part 13 
Part 14 
Part 15 



"Overview"; 

"Common Data Definitions"; 

"Framework"; 

"Call Control"; 

Sub-part 1: "Call Control Common Definitions"; 

Sub-part 2: "Generic Call Control SCF"; 

Sub-part 3: "Multi-Party Call Control SCF"; 

Sub-part 4: "Multi-Media Call Control SCF"; 

Sub-part 5: "Conference Call Control SCF"; 

"User Interaction SCF"; 

"Mobility SCF"; 

"Terminal Capabihties SCF"; 

"Data Session Control SCF"; 

"Generic Messaging SCF"; 

"Connectivity Manager SCF"; 

"Account Management SCF"; 

"Charging SCF". 

"Policy Management SCF"; 

"Presence and Availability Management SCF"; 

"Multi Media Messaging SCF"; 



(not part of 3GPP Release 6) 



(not part of 3GPP Release 6) 
(not part of 3GPP Release 6) 



(new in Release 6) 



The Mapping specification of the OSA APIs and network protocols (3GPP TR 29.998) is also structured as above. 
A mapping to network protocols is however not applicable for all Parts, but the numbering of Parts is kept. 
Also in case a Part is not supported in a Release, the numbering of the parts is maintained. 
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Table: Overview of the OSA APIs & Protocol Mappings 29.198 & 29.998-family 



OSA API specifications 29.198-family 


OSA API Mapping - 29.998-family 


29.198-01 


Overview 


29.998-01 


Overview 


29.198-02 


Common Data Definitions 


29.998-02 


Not Applicable 


29.198-03 


Framework 


29.998-03 


Not Applicable 


Call 
Control 
(CC) 
SCF 


29.198- 
04-1 

Common 
CC data 
definitions 


29.198- 
04-2 
Generic 
CCSCF 


29.198- 
04-3 
Multi- 
Party CC 
SCF 


29.198- 
04-4 
Multi- 
media CC 
SCF 


29.998-04-1 


Generic Call Control - CAP mapping 


29.998-04-2 


Generic Call Control — INAP mapping 


29.998-04-3 


Generic Call Control — Megaco mapping 


29.998-04-4 


Multiparty Call Control - ISC mapping 


29.198-05 


User Interaction SCF 


29.998-05-1 


User Interaction - CAP mapping 


29.998-05-2 


User Interaction — INAP mapping 


29.998-05-3 


User Interaction - Megaco mapping 


29.998-05-4 


User Interaction - SMS mapping 


29.198-06 


Mobility SCF 


29.998-06 


User Status and User Location - MAP mapping 


29.198-07 


Terminal Capabilities SCF 


29.998-07 


Not Applicable 


29.198-08 


Data Session Control SCF 


29.998-08 


Data Session Control - CAP mapping 


29.198-09 


Generic Messaging SCF 


29.998-09 


Not Applicable 


29.198-10 


Connectivity Manager SCF 


29.998-10 


Not Applicable 


29.198-11 


Account Management SCF 


29.998-11 


Not Applicable 


29.198-12 


Charging SCF 


29.998-12 


Not Applicable 


29.198-13 


Policy Management SCF 


29.998-13 


Not Applicable 


29.198-14 


Presence & Availability Management SCF 


29.998-14 


Not Applicable 


29.198-15 


Multi-media Messaging SCF 


29.998-15 


Not Applicable 



The following table explains how the various releases of ETSI, Parlay and 3GPP OSA specifications correspond. Each 
ETSI and 3GPP specification carries a version number and is updated independently. The frequency of 3GPP updates 
may be up to every 3 months, which is greater than that of ETSI or Parlay, therefore, while there is a corresponding 
version of 3GPP TS 29. 198 for every version of ETSI ES 201 915 or ES 202 915, there is not necessarily a 
corresponding version of the ETSI specification for each version of the 3GPP specification. For example, there is no 
ETSI/Parlay specification version which corresponds exactly to the 3GPP issue of TS 29.198 Release 4 from December 
2001. 

ETSI ES 201 915 / Parlay 3 / 3GPP TS 29.198 Release 4 (version 4.x.x) 



ETSI OSA Specification Set 


Parlay Phase 


3GPPTS 29.198 version 


- 


- 


Release 4, IVIarch 2001 Plenary 


- 


- 


Release 4, June 2001 Plenary 


ES201 915V.1.1.1 (complete release) 


Parlay 3.0 


Release 4, September 2001 Plenary 


- 


- 


Release 4, December 2001 Plenary 


ES201 915V.1.2.1 (complete release) 


Parlay 3.1 


Release 4, March 2002 Plenary 


ES201 915V.1.3.1 (complete release) 


Parlay 3.2 


Release 4, June 2002 Plenary 


- 


- 


Release 4, September 2002 Plenary 


ES201 915V.1.4.1 (complete release) 


Parlay 3.3 


Release 4, March 2003 Plenary 


- 


- 


Release 4, June 2003 Plenary 


- 


- 


Release 4, December 2003 Plenary 


- 


- 


Release 4, June 2004 Plenary 


ES201 91 5 v1 .5.1 (Partial Release) 


Parlay 3.4 


Release 4, September 2004 Plenary 


- 


- 


Release 4, December 2004 Plenary 


- 


- 


Release 4, December 2005 Plenary 


ES 201 915 v1. 6.1 (Partial Release) 


Parlay 3.5 


Release 4, June 2006 Plenary 
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ETSI ES 202 915 / Parlay 4 / 3GPP TS 29.198 Release 5 (version S.x.x) 



ETSI OSA Specification Set 


Parlay Phase 


3GPPTS 29.198 version 


- 


- 


Release 5, March 2002 Plenary 


ES 202 91 5 V.1 .1 .1 (complete release) 


Parlay 4.0 


Release 5, September 2002 Plenary 


ES202 915V.1.2.1 (not parts 9, 13, 14) 


Parlay 4.1 


Release 5, March 2003 Plenary 


- 


- 


Release 5, June 2003 Plenary 


- 


- 


Release 5, September 2003 Plenary 


- 


- 


Release 5, December 2003 Plenary 


- 


- 


Release 5, March 2004 Plenary 


- 


- 


Release 5, June 2004 Plenary 


ES202915V1.3.1, (v1.2.1 for parts 9, 13, 14) 


Parlay 4.2 


Release 5, September 2004 Plenary 


- 


- 


Release 5, December 2004 Plenary 


- 


- 


Release 5, June 2005 Plenary 


- 


- 


Release 5, December 2005 Plenary 


ES202 915V1.4.1, (v1.3.1 for parts 9, 13) 


Parlay 4.3 


Release 5, June 2006 Plenary 



ETSI ES 203 915 / Parlay 5 / 3GPP TS 29.198 Release 6 (version 6.x.x) 



ETSI OSA Specification Set 


Parlay Phase 


3GPPTS 29.198 version 


- 


- 


Release 6, June 2003 Plenary 


- 


- 


Release 6, December 2003 Plenary 


- 


- 


Release 6, June 2004 Plenary 


ES203 915V1.1.1 


Parlay 5.0 


Release 6, September 2004 Plenary 


- 


- 


Release 6, December 2004 Plenary 


- 


- 


Release 6, March 2005 Plenary 


- 


- 


Release 6, June 2005 Plenary 


- 


- 


Release 6, December 2005 Plenary 


ES203 915V1.2.1 


Parlay 5.1 


Release 6, June 2006 Plenary 
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Scope 



The present document is the first part of the 3GPP Specification defining the AppHcation Programming Interface (API) 
for Open Service Access (OS A), and provides an overview of the content and structure of the various parts of this 
specification, and of the relation to other standards documents . 

The OS A-specifications define an architecture that enables service application developers to make use of network 
functionality through an open standardised interface, i.e. the OSA APIs. The concepts and the functional architecture 
for the OSA are contained in 3GPP TS 23.198 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

This specification has been defined jointly between 3GPP TSG CT WG5, ETSI TISPAN and The Parlay Group, in co- 
operation with a number of JAIN^"^ Community member companies. 



References 



The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TR 21.905: "Vocabulary for 3GPP Specifications". 

[2] 3GPP TS 22.127: "Service Requirement for the Open Service Access (OSA); Stage 1". 

[3] 3GPP TS 23.198: "Open Service Access (OSA); Stage 2". 

[4] Void. 

[5] 3GPP TS 22.101: "Service Aspects; Service Principles". 

[6] Void. 

[7] 3GPP TS 29.002: "Mobile Application Part (MAP) specification". 

[8] 3GPP TS 29.078: "Customised Applications for Mobile network Enhanced Logic (CAMEL); 

CAMEL AppUcation Part (CAP) specification". 



3 Definitions and abbreviations 

3.1 Definitions 

For the purposes of the present document, the terms and definitions given in 3GPP TS 22.101 [5] and the following 
apply. 

Applications: Services, which are designed using Service Capability Features (SCFs). 

Gateway: Synonym for Service Capability Server (SCS). From the viewpoint of applications, an SCS can be seen as a 
gateway to the core network. 

HE-VASP: Home Environment Value Added Service Provider. This is a VASP that has an agreement with the Home 
Environment to provide services. 
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Home Environment: responsible for overall provision of services to users. 

Local Service: A service, which can be exclusively provided in the current serving network by a Value Added Service 
Provider. 

OSA Interface: Standardised Interface used by application to access service capability features. 

Personal Service Environment (PSE): contains personalised information defining how subscribed services are 
provided and presented towards the user. The Personal Service Environment is defined in terms of one or more User 
Profiles. 

Service Capabilities: Bearers defined by parameters, and/or mechanisms needed to realise services. These are within 
networks and under network control. 

Service Capability Feature (SCF): Functionality offered by service capabilities that are accessible via the standardised 
OSA interface. 

Service Capability Server (SCS): Functional Entity providing OSA interfaces towards an application. 

Service: term used as an alternative for Service Capability Feature in this specification. 

User Interface Profile: Contains information to present the personalised user interface within the capabilities of the 
terminal and serving network. 

User Profile: This is a label identifying a combination of one user interface profile, and one user services profile. 

User Services Profile: Contains identification of subscriber services, their status and reference to service preferences. 

Value Added Service Provider: provides services other than basic telecommunications service for which additional 
charges may be incurred. 

Virtual Home Environment: A concept for personal service environment portability across network boundaries and 
between terminals. 

3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in 3GPP TR 21.905 [1] and the following apply. 

API Application Programming Interface 

CAMEL Customised Application for Mobile network Enhanced Logic 

CAP CAMEL Application Part 

CSE CAMEL Service Environment 

FW Framework 

HE Home Environment 

HE-VASP Home Environment - Value Added Service Provider 

HLR Home Location Register 

INAP Intelligent Networks Application Part 

IDL Interface Description Language 

JSR Java"^ Specification Request 

MAP Mobile Application Part 

ME Mobile Equipment 

MExE Mobile Station (Application) Execution Environment 

MS Mobile Station 

MSC Mobile Switching Centre 

OSA Open Service Access 

PLMN Public Land Mobile Network 

PSE Personal Service Environment 

RMI JavaT"^ Remote Method Invocation 

SAT SIM AppHcation Tool-Kit 

SCF Service Capability Feature 

SCP Service Control Point 

SCS Service Capability Server 

SIM Subscriber Identity Module 

SMS Short Message Service 
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SMTP Simple Mail Transfer Protocol 

SOAP Simple Object Access Protocol 

SPA Service Provider API 

UE User Equipment 

USIM Universal Subscriber Identity Module 

VLR Visited Location Register 

VASP Value Added Service Provider 

VHE Virtual Home Environment 

WAP Wireless Application Protocol 

WGP Wireless Gateway Proxy 

WPP Wireless Push Proxy 

WSDL Web Services Definition Language 

XML Extensible Markup Language 



Open Service Access APIs 



The OS A-specifications define an architecture that enables service application developers to make use of network 
functionality through an open standardised interface, i.e. the OSA APIs. The network functionality is describes as 
Service Capability Features (SCFs) or Services. The OSA Framework is a general component in support of Services 
(Service Capabilities) and Applications. The concepts and the functional architecture for the OSA are contained in 
3GPP TS 23.198 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The OSA API is split into three types of interface classes, Service and Framework (FW). 

Interface classes between the Applications and the Framework (FW), that provide applications with basic 
mechanisms (e.g. Authentication ) that enable them to make use of the service capabilities in the network. 

Interface classes between Applications and SCFs, which are individual services that may be required by the 
client to enable the running of third party applications over the interface e.g. Messaging type service. 

Interface classes between the Framework (FW) and the SCFs, that provide the mechanisms necessary for a 
multi-vendor environment. 

These interfaces represent interfaces 1, 2 and 3 in Figure 1 below. The other interfaces are not yet part of the scope of 
the work. 
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Enterprise 
operator 
admin tool 



Not in the scope 
of the present API 
version 




Client 
Application 




Not in the scope 
of the present API 
version 



Service 

supplier 

admin tool 



Telecom Network 



Figure 1: 

Within the OS A concept a set of Service Capabihty Features (SCFs) has been specified. The OSA documentation is 
structured in parts. The first part (the present document) contains an overview, the second part contains common data 
definitions, the third part the Framework interfaces and the following parts contain the description of the SCFs. 

NOTE: The terms 'Service' and 'Service Capability Feature' are used as alternatives for the same concept in the 
present document. In the OSA API itself the SCFs as identified in the 3GPP requirements and architecture 
are reflected as 'service', in terms like service instance lifecycle manager, service Discovery. 



5 Structure of the OSA API (29.198) and Mapping 

(29.998) documents 

The Open Service Access (OSA) Application Programming Interface (API) specifications consist of two sets of 
documents: 

API specification (3GPP TS 29.198) 

The Parts of 29.198 - apart from Part 1 (the present document) and Part 2 - define the interfaces, parameters and 

state models that belong to the API specification. UML (Unified Modelling Language) is used to specify the 

interface classes. 

As such it provides a UML interface class description of the methods (API calls) supported by that interface and the 

relevant parameters and types. The interfaces are specified in IDL (Interface Description Language), WSDL (Web 

Services Definition Language) and in Java^"^. 

Mapping specification of tlie OSA APIs and network protocols (3GPP TR 29.998) 

The Parts of 29.998 contain a possible mapping from the APIs defined in 29. 198 to various network protocols (i.e. 
MAP [7], CAP [8], etc.). It is an informative document, since this mapping is considered as implementation- / 
vendor-dependent. On the other hand this mapping will provide potential service designers with a better 
understanding of the relationship of the OSA API interface classes and the behaviour of the network associated to 
these interface classes. 

The purpose of the OSA API is to shield the complexity of the network, its protocols and specific implementation from 
the applications. This means that applications do not have to be aware of the network nodes, a Service Capability Server 
interacts with, in order to provide the SCFs to the appUcation. The specific underlying network and its protocols are 
transparent to the application. 
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The API specification (3GPP TS 29.198) is structured in the following Parts: 

29.198-1 Parti: Overview 

29.198-2 Part 2: Common Data Definitions 

29.198-3 Part 3: Framework 

29. 198-4 Part 4: Call Control SCF 

29. 198-5 Part 5: User Interaction SCF 

29.198-6 Part 6: Mobility SCF 

29.198-7 Part?: Terminal Capabilities SCF 

29. 198-8 Part 8: Data Session Control SCF 

29. 198-9 Part 9: Generic Messaging SCF 

29.198-10 Part 10: Connectivity Manager SCF 

29.198-11 Part 11: Account Management SCF 

29.198-12 Part 12: Charging SCF 

29 . 1 98 - 1 3 Part 1 3 : Policy Management S CF 

29. 198-14 Part 14: Presence & Availability Management SCF 

29. 198-15 Part 15: Multi-media Messaging (MM) Service Capability Feature (SCF) 

The Mapping specification of the OSA APIs and network protocols (3GPP TR 29.998) is also structured as above. 
A mapping to network protocols is however not applicable for all Parts, but the numbering of Parts is kept. 
Also in case a Part is not supported in a Release, the numbering of the parts is maintained. 

Structure of the parts of TS 29.198 

The parts with API specification themselves are structured as follows: 

The Sequence diagrams give the reader a practical idea of how each of the SCF is implemented. 

The Class relationships clause shows how each of the interfaces applicable to the SCF, relate to one another. 

The Interface specification clause describes in detail each of the interfaces shown within the Class diagram part. 

The State Transition Diagrams (STD) show the progression of internal processes either in the application, or 

Gateway. 

The Data definitions clauses show a detailed expansion of each of the data types associated with the methods 
within the classes. It is to be noted that some data types are used in other methods and classes and are therefore 
defined within the Common Data types part of this specification. 

The OSA API is defined using UML and as such is technology independent. OSA can be realised in a number of ways 
and in addition to the UML defined OSA API, the OSA specification includes: 

A normative annex with the OSA API in IDL that specifies the CORB A distribution technology realisation 

An informative annex with the OSA API in WSDL that specifies the SOAP/HTTP distribution technology 
realisation 

An informative annex that references the OSA API in JavaT"^ (known as JAIN'""^ Service Provider API) that 
specifies the Java'"^ local API technology realisation 
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6 Methodology 

Following is a description of the methodology used for the establishment of API specification for OS A. 

6.1 Tools and Languages 

The Unified Modelling Language (UML) ( http://www.omg.org/uml ) is used as the means to specify class and state 
transition diagrams. 

6.2 Packaging 

A hierarchical packaging scheme is used to avoid polluting the global name space. The root is defined as: 
org.csapi 

6.3 Colours 

For clarity, class diagrams follow a certain colour scheme. Blue for application interface packages and yellow for all the 
others. 

6.4 Naming scheme 

The following naming scheme is used for documentation. 
packages 

lowercase. 

Using the domain-based naming (For example, org.csapi) 
classes, structures and types. Start with T 

TpCapitalizedWithlnternalWordsAlsoCapitalized 
Exception class: 

TpClassNameEndsWithExceptionandP_UPPER_CASE_WITH_UNDERSCORES_AND_START_WITH_P 
Interface. Start with Ip: 

IpThisIsAnlnterface 
constants: 

P_UPPER_CASE_WITH_UNDERSCORES_AND_START_WITH_P 
methods: 

firstWordLowerCaseButlnternalWordsCapitalizedO 
method's parameters 

firstWordLowerCaseButlnternalWordsCapitalized 
collections (set, array or list types) 

TpCoUectionEndsWithSet 
class/structure members 
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FirstWordAndlnternalWordsCapitalized 
Spaces in-between words are not allowed. 

6.5 State Transition Diagram text and text symbols 

The descriptions of the State Transitions in the State Transition Diagrams follow the convention: 

when_this_event_is_received [guard condition is true] /do_this_action '^send_this_message 

Furthermore, text underneath a line through the middle of a State indicates an exit or entry event (normally specified 
which one). 

6.6 Exception handling and passing results 

OSA methods communicate errors in the form of exceptions. OS A methods themselves always use the return 
parameter to pass results. If no results are to be returned a void is used instead of the return parameter. In order to 
support mapping to as many languages as possible, no method out parameters are allowed. 

6.7 References 

In the interface specification whenever Interface parameters are to be passed as an in parameter, they are done so by 
reference, and the "Ref" suffix is appended to their corresponding type (e.g. IpAnlnterfaceRef aninterface), a reference 
can also be viewed as a logical indirection. 



Original type 


IN parameter declaration 


Iplnterface 


parm : IN IplnterfaceRef 



6.8 Strings and Collections 

For character strings, the String data type is used without regard to the maximum length of the string. 

For homogeneous collections of instances of a particular data type the following naming scheme is used: <datatype>Set 

6.9 Prefixes 

OSA constants and data types are defined in the global name space: org.csapi. 
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7. Introduction to OSA APIs 

This section contains the general rules that were followed by the design of the OSA APIs and advice for how to use 
them. Note however that exceptions to these "rules" may exist and that examples are not exhaustive. 

7.1 Interface Types 

In the OSA specifications different types of interfaces are distinguished: 

• Application side (callback) interfaces. This type of interface needs to be implemented by an application (client) 
and the name of such an interface is prefixed with "IpApp". 



• 



• 



• 



Interfaces of an SCF that are used by the Framework. The name of this type of server interface is prefixed with 
"IpSvc". 

Application side interfaces and SCF interfaces that are shared. The name of this type of interface is prefixed with 
"IpClient" 

Interfaces of the Framework that are used by an SCF. The name of this type of server interface is prefixed with 
"IpFw". 



The name of all other interfaces of the Framework and SCFs that are used by an application, is prefixed with "Ip" 



7.2 Service Factory 



For each application that uses an SCF, a separate object is created to handle all communication to the application. This 
object is referred to as the Service Manager. The pattern used is often referred to as the Factory Pattern. The Service 
Manager creates any new objects in the SCF. The Service Manager and all the objects created by it are referred to as 
"service instance". 

Once an application is granted access to an SCF, the Framework requests the SCF to create a new Service Manager. 
The reference to this Service Manager is provided to the application. From this moment onwards the application can 
start using the SCF. 

7.3 Use of Sessions 

A session is a series of interactions between two communication end points that occur during the span of a single 
connection. An example is all operations to set-up, control, and tear down a (multi-party) call. A session is identified by 
a Session ID. This ID is unique within the scope of a service instance and can be related to session numbers used in the 
network. 

7.4 Interfaces and Sessions 

Some interfaces have a one-to-one relation with a session. For every session there is a separate interface instance. In this 
case, this instance of an interface represents the session. All methods invoked on such an interface operate on the same 
session. These interfaces make no use of Session IDs. 

Other interfaces can represent multiple sessions. The underlying implementation can then either create an instance per 
session or it can handle multiple sessions per instance (e.g., to combat extensive resource usage). When a method on 
such an interface is invoked it requires a Session ID to uniquely identify the session to which it applies. 

7.5 Callback Interfaces 

Some OSA interfaces require an application to register a callback interface. This interface resides on the client 
(application) side and is used by the server (service) to report events, results, and errors. An application shall register its 
callback interface as soon as the corresponding server side interface is created. 
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7.6 Setting Callbacks 



Two methods are available in every service interface that can be used for setting the callback interface: setCallback() 
and setCallbackWithSessionID(). Interfaces that do not use sessions shall (obviously) only implement setCallback(). An 
invocation of setCallbackWithSessionID() on such interfaces shall result in an exception (P_TASK_REFUSED). 

Interfaces that use sessions shall only implement setCallbackWithSessionID(). An invocation of setCallback() on such 
interfaces shall result in an exception (P_TASK_REFUSED). This regardless of whether an interface instance actually 
implements multiple sessions or not. 

7.7 Synchronous versus Asynchronous Methods 

Two types of methods exist in OS A interfaces. When a method does not require the SCS to contact other nodes in the 
network it is implemented as a synchronous method. When the method returns, the result (if applicable) of the operation 
is provided to the application. When an error occurs, an exception is thrown. Examples of synchronous methods are 
methods to retrieve data that is available in the SCS and methods that create an object. 

In other cases, a method requires the SCS to contact other nodes in the network. There can be a delay between the 
moment a message is sent into the network and the moment that the result is received or an error is detected. To prevent 
that the application is blocked or that an application has to "guess" whether there is a problem in the SCS, these types of 
methods are made asynchronous. 

An asynchronous method of an interface can be recognized by the fact that its name ends with "Req" (from request) and 
that in the corresponding callback interface two methods are included with the same name but ending with "Res" (from 
result) and "Err" (from error) instead. When no error has occurred, the "Res" method will be invoked when the result is 
available. In case an error has been detected, the "Err" method is invoked. Problems that can be detected by the SCS 
itself (for instance illegal parameter values) will result in exceptions being thrown when the "Req" method is called. 
After a "Req" method has returned, only errors shall be reported. 

Because it is possible that multiple requests can be done in parallel (invoking multiple times a "Req" method without 
having received a result or error) a mechanism is needed to link requests with responses. Therefore, the "Req" method 
returns an Assignment ID and the "Res" and "Err" methods have this Assignment ID as input parameter. For session 
based interfaces the Session ID can be used also. 

Some "Req" methods can result in multiple "Res" methods being invoked. However, the corresponding "Err" method 
will never be invoked more than once. 

Note that methods on client side interfaces shall never raise an exception unless this is explicitly described in the 
specification. 

Some methods switch on/off reports (for instance triggered location reports). These methods are of a different kind and 
do not follow the pattern that is described in this section. 

A deadlock is a potential danger when using asynchronous methods, especially in single threaded systems. It can occur 
that client and server are waiting for each other for a task to be completed. It is considered good practice to build in 
mechanisms to prevent deadlock from occurring, for instance by using multiple threads or using time-outs on remote 
method calls. 

7.8 Out Parameters 

Methods used in OSA interfaces only have input parameters. Any result can only be reported by a return value. If 
multiple values need to be returned, a datatype is required that consists of a sequence of values. A value of this datatype 
is then returned by a method. This approach has been chosen because not all middleware solutions are (or may be) 
capable of dealing with (multiple) output parameters. 



7.9 Exception Hierarchy 



Exceptions are organized in an exception hierarchy. For the general exceptions and for each service type an abstract 
exception class is defined. Advantage for an application programmer is that (s)he does not need to catch all the specific 
exceptions, but may catch only the abstract exceptions. 
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Note however that the exception hierarchy is only available when the applicable OSA realisation supports this. 
Java™ does, but CORBA and SOAP does not. 



7.10 Common Exceptions 



Exception TpCommonExceptions can be thrown by any method. It is an aggregate of a number of general problems. To 
prevent that each method's signature requires all these exceptions they are all included in a single exception class. 

The following rules apply on when what type of general exception shall be thrown: 

• P_RESOURCES_UNAVAILABLE is thrown when a physical resource in the network is not available. 

• P_INVALID_STATE is thrown when a method is called that is not allowed in the state that the OSA state 
machines are in. 

• P_TASK_CANCELLED is thrown in case of a temporary problem. 

• P_TASK_NO_CALLBACK_ADDRESS_SET is thrown when no callback address has been set. 

• P_METHOD_NOT_SUPPORTED is thrown when the application initiates methods that are either not according 
to the Service Level Agreement or not supported in the SCS. 

• P_TASK_REFUSED is thrown in case of a problem that is not temporary and when none of the other common 
or dedicated exceptions apply. 

Note that methods on application side callback interfaces shall never raise an exception unless explicitly stated in the 
specification. 

7.11 Use of NULL 

The OSA specifications contain references to the NULL value to indicate the absence of a certain parameter. An 
example where this is used is for specifying NULL as a callback reference. 

A parameter description for parameters of any datatype can indicate that NULL is a possible value. The realisation of 
NULL can differ per technology. A NULL value for a sequence in CORBA means that all its members shall be NULL 
while in Java'"^ the whole structure could be NULL. 

Note that it always shall be stated in the specification when a NULL value can be expected. 



7.12 Notification Handling 



Several OSA SCFs provide a mechanism for creating and receiving notifications. A notification is the reporting of an 
event occurring in the network or SCS. Examples of notifications are answer, busy, and on hook events. 

This section describes the general mechanism of notification handling. Note that it might not apply (exactly) to every 
API. 

There are two types of notifications. One that is created by an application and one that is controlled by the network. The 
first type normally is used when an ASP is responsible for service provisioning and has to create its own notifications in 
order to be able to serve subscribers. The second type is used when the network operator does service provisioning. The 
network operator creates the notifications and an application only needs to handle them. 

Note that normally both mechanisms will not be used by one application. However, the OSA interfaces do not prohibit 
this. 

Another way to distinguish notifications is by monitor mode. Notifications can be requested in either NOTIFY or 
INTERRUPT mode. When requested in NOTIFY mode, the notifications is reported to the application but the SCS 
continues processing. For notifications requested in INTERRUPT mode, processing in the SCS is suspended when the 
notification is reported to the application. The application has to instruct the SCS explicitly (within a certain maximum 
time) how to proceed the processing. Note that not all SCFs support notifications in INTERRUPT mode. 
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When a notification is created and when an application registers for network controlled notifications a callback interface 
needs to be provided. This callback interface is used for reporting the notifications. There are however a few things that 
are worth mentioning here: 



• 



• 



• 



Each time a (set of) notifications(s) is created, a callback is specified that is used for reporting the requested 
notifications. This callback interface may be the same, but may also differ. The assignment ID can be used to 
link a notification report to the creation of registration. 

Registering a callback for network controlled notifications needs to be done only once. The callback interface 
that is provided may be the same as the one used for creating a notification (note again that it is however not 
recommended to used both mechanisms in the same application). 

The callback specified when creating or registering for events overrules the callback set with setCallback() or 
setCallbackWithSessionID(). This means that this one will NOT be used for reporting notifications . It will 
however be used for all other methods that require the callback interface. 

Only if NULL is provided as callback interface reference, the callback interface that was set using setCallback() 
or setCallbackWithSessionlDO is used for reporting notifications. 

It is possible to recreate a (set of) notification(s) or re-register for notifications. This is only useful when 
providing a different callback interface reference. In this case, the last provided interface is used for reporting 
notifications. The earlier provided callback interface is used as "backup" interface (this can be the one provided 
with setCallbackO or setCallbackWithSessionID() if NULL was provided initially). Notifications are reported on 
this interface when calls to the most recent provided callback interface fail (object providing the interface is 
crashed or overloaded). When re-creating or re-registering, the same assignment ID is returned. 



8 Backwards Compatibility Considerations 

The backwards compatibility rules described below are intended to enable an older client to continue to interwork with 
a newer server or gateway. 

8.1 Guidelines to enable backwards compatibility in 
implementations 

1) The Gateway should require the usage of Framework versions and service versions. All Applications should 
use these parameters. 

2) The IDL version parameter should not be used when generating the IDL. 

3) If there are multiple versions of an SCF they should be all registered with the Framework, and the SCF should 
create an instance of the version requested by the application when a new service manager is created. 



8.2 Rule summary 



The following types of changes can be made to these specifications while preserving backwards compatibiUty, 
everything beyond these changes is not allowed. 

8.2.1 Server side permitted ciianges 

• Addition of a new interface 

• Addition of a new method to an existing or new interface 

• Addition and removal of exceptions if the implementation uses the Application version as described above. 

8.2.2 Client side permitted cinanges 

• Addition of a new interface 
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• Addition of a new method 

Note: The version the client requests should be used to indicate which interfaces and methods are supported on 
the client side. 

• Addition and removal of exceptions if the implementation uses the Application version as described above. 

8.2.3 Data type permitted changes 

• Elements can be added to "sequence" data types. Care should be taken when adding elements to data types that 
are sent back to the client: The client may be outdated and thus not be able to interpret the new element. Only 
information that has not been available before (and therefore is not expected by the client) may be transferred 
in added elements. Information that has been available before (and therefore possibly expected by the client) 
may not be modified in any way. 

• Elements can be added to "tagged choice of data elements" data types, if they are always sent from client to 
server (either within a parameter of a server side method, or within the result of a client side method. 

Every change beyond the rules listed above is forbidden. In particular, changes like the following should not be done: 

Changing the order of enumerated types 

Changing method signatures 

• Removing or renaming methods 

8.3 Implementation Guidelines for Server Programmers 

• If methods are added at the client side, the server should call them only if it can be sure that the client has 
implemented them. Basically, this means the server needs to make sure that the client supports the release, 
where the new methods have been introduced, or a later one. 

• Servers could ensure that references to dynamically created objects (service managers or calls) remain valid 
even after a server upgrade. An alternative method is to be able to make so called graceful close of old 
versions and running the new version in parallel. The old version will not allow any new requests but will 
allow existing ones to execute until they are finished. 

8.4 Implementation Guidelines for Client Programmers 

• The backwards compatibility rules allow for "smooth" upgrades to new Parlay/OSA releases in the Gateway. 
All existing functionality should still work without any changes in the client. Client programmers need to 
change code only to enhance it; they should never need to change code just to adopt it to the new release. 
Care should be taken when supporting features of a new release. The moment a client application use newer 
release features, it should then support all of the client side features for that newer release, otherwise the sever 
may invoke newer release methods on the client and the client will not respond. 

8.5 Tracking the changes in the specifications 
8.5.1 New Tag 

If a client side interface is added, or methods are added to an existing interface, the new methods are marked with a 
UML stereotype "New". 

This tag is merely a hint for the programmer. 
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8.5.2 Deprecated Tag 

If interfaces, methods or service properties are deemed outdated or broken, the items are marked with a UML stereotype 
"Deprecated". The tag indicates that they are supported by this Framework or SCF release, but that they will not 
necessarily be supported in subsequent releases. The respective items may be removed in the specification release. 

The tag is a hint for the client programmer that an update to their client applications may be necessary. 

8.6 Technology realization rules 

8.6.1 Corba IDL Rules 

In addition to the rules identified above, in order to ensure backwards compatibility of the IDL code, the following rules 
shall be followed in updating this specification: 

• IDL version numbering should not be used when generating the IDL. 

8.6.2 Java rules 

In addition to the rules identified above, in order to ensure backwards compatibility of the J2EE and J2SE code, the 
following rules shall be followed in updating this specification: 

• When elements are added to "sequence" data types, the Java constructor for these data types is updated with 
the new elements when the Java code is re-generated. The old constructor, without the new elements, shall be 
manually included in the generated Java code and marked as deprecated. 

8.7 Rules for removal of deprecated items from the 
specifications 



• 



At the start of each major 3GPP Release n (during the development phase of a new release, prior to the closure 
of the release to new functionality), we delete, using change requests, all deprecated methods and other 
deprecated items, which are identified as deprecated in the most recent version of the Release n-2 edition of 
specifications. 

When deleting deprecated methods, any unused data types can be deleted using the CR process. 

At the start of each major release, the «new» stereotypes that were present in the specifications prior to this 
release are deleted. CRs are not required for this. 

Methods or stereotypes are never deleted following closure of a release to new functionality. 

Names of deleted methods are never re-used. 

Exceptionally, we may choose not to delete certain deprecated methods, in the interest of preserving 
backwards compatibility. 
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Annex A (normative): 
OMG IDL 

A.1 Tools and Languages 

The Object Management Group's (OMG) ( http://www.omg.org/) Interface Definition Language (IDL) is used as a 
means to programmatically define the interfaces. IDL files are either generated manually from class diagrams or by 
using a UML tool. In the case IDLs are manually written and/or being corrected manually, correctness has been verified 
using a CORBA2 (orbos/97-02-25) compliant IDL compiler, e.g. ( http://iava.sun.com/products/idk/idl/index.html) . 

A.2 Namespace 

The used namespace in CORBA IDL is org.csapi. 

A.3 Object References 

In CORBA IDL it is not needed to explicitly indicate a reference to an object. Where the specifications explicitly 
indicate a reference to an object by adding "Ref to the object type, this addition is removed when mapped to the IDL. 

Example 1: struct TpMultiPartyCallldentifier { 

IpMultiPartyCall CallReference; 
TpSessionID CallSessionID; 

}; 



A.4 Mapping of Datatypes 
A.4.1 Basic Datatypes 

In IDL, the data type String is typedefed (see Note below) from the CORBA primitive string. This CORBA primitive is 
made up of a length and a variable array of byte. 

NOTE: A typedef is a type definition declaration in IDL. 

TpBoolean maps to a CORBA boolean, Tplnt32 to a CORBA long, TpFloat to a CORBA float, and TpOctet to a 
CORBA octet. 

A.4.2 Constants 

All constants are mapped to a CORBA const of type Tplnt32. 
Example 2: const Tplnt32 P_TASK_REFUSED = 14; 

A.4.3 Collections 

In OMG IDL, collections (Numbered Set and Numbered List) map to a sequence of the data type. A CORBA sequence 
is implicitly made of a length and a variable array of elements of the same type. 

Example 3: typedef sequence<TpSessionID> TpSessionlDSet; 



ETSI 



3GPP TS 29.198-01 version 6.4.1 Release 6 23 ETSI TS 129 198-1 V6.4.1 (2006-07) 

Collection types can be implemented (for example, in C++) as a structure containing an integer for the number part, 
and an array for the data part. 

Example 4: The TpAddressSet data type may be defined in C++ as: 

typedef struct { 

short number; 

TpAddress address []; 
} TpAddressSet; 

The array "address" is allocated dynamically with the exact number of required TpAddress elements based on 
"number". 

A.4.4 Sequences 

In OMG IDL sequences map to a CORBA Struct. 

Example 5: struct TpAddress { 

TpAddressPlan Plan; 

TpString AddrString; 

TpString Name; 

Tp Addres s Pre sentation Pre sentation; 

TpAddressScreening Screening; 

TpString SubAddressString; 



A.4.5 Enumerations 

In OMG IDL enumerations map to a CORBA enum. 

Example 6: enum TpAddressScreening { 

P_ADDRESS_SCREENING_UNDEFINED , 
P_ADDRESS_SCREENING_USER_VERIFIED_PASSED, 
P_ADDRESS_SCREENING_USER_NOT_VERIFIED, 
P_ADDRES S_SCREENING_USER_VERIFIED_FAILED , 
P_ADDRES S_SCREENING_NETWORK 



A.4.6 Choices 

A choice maps to a CORBA union. For entries that do not have a corresponding type (defined as NULL in the 
specification) no union entry is generated. These entries are grouped in the default clause where NULL is replaced by 
short and the entry name (Undefined) by the name Dummy. When there are no NULL entries, the default clause is not 
generated. 

Example 7: union TpCallAdditionalErrorlnfo switch (TpCallErrorType) { 

case P_CALL_ERROR_INVALID_ADDRESS: Tp Addres sError CallErrorlnvalidAddress; 
default: short Dummy; 

}; 

Example 8: union TpCallChargeOrder switch(TpCallChargeOrderCategory) { 

case P_CALL_CHARGE_TRANSPARENT: TpOctetSet TransparentCharge; 
case P_CALL_CHARGE_PREDEFINED_SET: Tplnt32 ChargePlan; 
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A.5 Use of NULL 



CORBA allows the value NULL to be used for object references only. When the specification mentions NULL as 
possible value of a struct, it means that each object reference in the struct shall be set to NULL. NULL does not apply to 
other datatypes then object references. 



A.6 Exceptions 



The TpCommonExceptions is mapped to a CORBA exception containing a data item of type Tplnt32 to indicate the 
type of general exception and extra information of type TpString. 

Example 9: exception TpCommonExceptions { 
Tplnt32 ExceptionType; 
TpString Extralnformation; 

}; 

All other exceptions are also mapped to CORBA exceptions but containing a data item of type TpString to indicate 
additional information. 

Example 10: exception P_INVALID_ASSIGNMENT_ID { 
TpString Extralnformation; 

}; 



A.7 Naming space across CORBA modules 

The following shows the naming space used in this specification. 

module org { 

module csapi { 

/* The fully qualified name of the following constant is org: : csapi : :P_THIS_IS_AN_OSA_GLOBAL_CONST 

*/ 

const long P_THIS„IS_AN_OSA_GLOBAL„CONST= 1999; 

// Add other OSA global constants and types here 

module fw ( 

/* no scoping required to access P_THIS_IS_AN_OSA_GLOBAL_CONST */ 

const long P_FW_CONST= P_THIS_IS_AN_OSA_GLOBAL_CONST; 

}; 

module mm ( 

// scoping required to access P_FW_CONST 

const long P_M_CONST= fw: : P_FW_CONST; 

}; 

}; 
}; 
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Annex B (informative): 
W3C WSDL 

B.1 Tools and Languages 

The W3C ( http://www.w3c.org) WSDL (Web Services Definition Language) is an XML format for describing network 
services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented 
information. WSDL files are generated from the UML. The generated WSDL files are verified using WSDL compilers. 
The WSDL is based on W3C WSDL L L The approach to generating the WSDL is documented separately. This 
document covers the type mappings, and should be viewed as reference only as the tools will generate all these 
mappings automatically. 



B.2 Proposed Namespaces for the OSA WSDL 

Namespaces are an important part of an XML Schema. They are used to qualify the source of a particular XML 
element. 

There are several XML/SOAP/WSDL related Namespaces which are used within each of the WSDL documents. The 
Namespace Prefix and the associated Namespace are noted below. 

xmlns:wsdl = ' http://schemas.xmlsoap.org/wsdl/ ' 

xmlns : soap= ' http://schemas.xmlsoap.org/wsdl/soap/ ' 

xmlns : SO AP-ENC= ' http://schemas.xmlsoap.org/soap/encoding/ ' 

xmlns:xsd=' http://www. w3c.org/2001/XMLSchema ' 

xmlns:addressing="http://www. w3.org/2005/08/addressing" 

There are also OSA specific namespaces that are used within the OSA WSDL documents. The OSA related namespaces 
present within each WSDL document depends on the WSDL document and which WSDL documents it imports. The 
guidelines used to derive these namespaces are: 

The root namespace for the OSA WSDL and XML schemas is http://www.csapi.org/ 

There is one WSDL document generated for each interface. The WSDL document will have the name of the 
UML component with the extension '.wsdl' For each WSDL document generated the following 
additional namespaces will be included: 

xmlns :<component name>=' http://www.csapi.org /<component name>/wsdr 

xmlns :<component name>xsd=' http://www.csapi.org /<component name>/schema' 

For each OSA WSDL document which is referenced by an import statement within the current WSDL 
document then the following additional namespaces will be included. 

xmlns :<imported component name>=' http://www.csapi.org/ <imported component namo/wsdl' 

xmlns :<imported component name>xsd=' http://www.csapi.org/ <imported component name>/schema' 

• Attributes that require a QName value shall use the appropriate Namespace Prefix (as defined in the 
definitions element of the wsdl file) to qualify the element being referenced. 

The namespaces are defined within the 'definitions' element of a wsdl document. For example, the definitions element 
of the am_logical.wsdl document would look like: 

<def initions 

name= ' am_logical ' 

tar get Name space= ' http : //www . csapi . org/am/wsdl ' 
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xmlns= ' http : // schema s . xmlsoap . org/wsdl/ ' 

xmlns : wsdl= ' http : / /schema s . xmlsoap .org/wsdl/ ' 

xmlns : soap= ' http : // schema s . xmlsoap . org/wsdl /soap/ ' 

xmlns : SOAP-ENC= ' http: //schemas . xmlsoap. org/ soap /encoding/ ' 

xmlns : xsd= ' http: //www. w3 . org/200 1/XMLSchema ' 

xmlns : addressing="http: //www. w3 . org/2005/08 /addressing" 

xmlns : am= ' http : //www. csapi . org/am/wsdl ' 

xmlns : amxsd= ' http : //www. csapi . org /am/ schema ' 

xmlns : osa= ' http : //www. csapi . org/osa/wsdl ' 

xmlns : osaxsd= ' http : //www. csapi . or g/osa/ schema ' > 

< import names pa ce= ' http : //www. csapi .org/osa/wsdl ' 
location= ' osa_logical . wsdl ' /> 



B.3 Object References 



Object references are used to identify particular remote object instances. Object references are used in two ways: 

1) Passed as a parameter within a metliod to a remote object or passed as an attribute of a structured type 
parameter within a method to the remote object. 

Included within a message to identify the object for which the message is intended. 

Within the context of Web Services, an object reference can be represented as by an Endpoint Reference as documented 
in WS-Addressing. This is the standard approach for passing references in Web Services. 

When an object reference is passed as a parameter, the parameter type is defined as a reference to an interface. When an 
object reference is an attribute of a structured type, that attribute is defined as a reference to an interface. Each interface 
will have a corresponding reference element associated with it. The interface reference will be defined as: 

<element name="r)a:nelnterf ace" type=" addressing : EndpointRef erenceType" /> 

where name is the name of the particular interface as defined in the UML. 

When an object reference is used to identify the intended recipient of a message, then the To and Action elements from 
the WS-Addressing schema should be used as outlined in this standard. 



B.4 Mapping UML Data Types to XML Schema 



B.4.1 Data Types 

The following mappings apply to the basic data types: 



UML 


Schema Realisation 


TpBoolean 


xsdiboolean 


Tplnt32 


xsdiint 


Tplnt64 


xsdiong 


TpFloat 


xsdifloat 


TpOctet 


xsdiunsignedByte 


TpString 


xsdistring 


TpLongString 


xsdistring 


TpAny 


xsdianyType 



B.4.1. 2 «Constant» 

The UML Constant data type contains the following attributes: 

• Name 

• Constant Value 
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These types are not mapped to WSDL, as there is no concept of a constant value in schema. It may be possible in the 
future to add a constant value using a restriction on a base type. The lack of this mapping does not limit the ability to 
send constant values in messages. 

B.4.1.3 «NameValuePair» 

The UML NameValuePair data type contains the following attributes: 

• Name 

• Attributes 

Name 
This type would then map to the following XML Schema construct: 

<xsd: simpleType name="Nanie"> 

<xsd: restriction base="xsd; string"> 

<xsd: enumeration value="Attribute-Name" /> 
<xsd: enumeration value="Attribute-Name" /> 

<xsd: enumeration value="Attribute-Name" /> 
</xsd: restriction> 
</xsd; simpleType> 

B.4.1 .4 «SequenceOfDataElements» 

The UML SequenceOfDataElements data type contains the following attributes: 

• Name 

• Roles 

Name 
Type 
This type would then map to the following XML Schema construct: 

<xsd; complexType name="Waine" 
<xsd; sequence> 
<xsd: element 

Name = " Role-Name" 
tYPe=" Role-Type" /> 
<xsd: element 

¥lame=" Role-Name" 
tYpe=" Role-Type" /> 

<xsd; element 

Name=" Role-Name" 
type=" Role-Type" /> 

</xsd: sequence> 
</xsd; complexType> 

B.4.1. 5 «TypeDef» 

The UML TypeDef data type contains the following attributes: 

• Name 

• ImplementationType 

Type definitions (typedefs) do not exist directly in schema so these types are unwound to their base data types. E.g.: 
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UML 


Schema Realisation 


TpCallAlertingMechanism 


xsd:int 


TpAccessType 


xsd:string 



This support could be added in the future using restriction on a base type. 

B.4.1 .6 «NumberedSetOfDataElements» 

The UML NumberedSetOfDataElements data type for sequences types contains the following attributes: 

• Name 

• ImplementationType 

This type would then map to the following XML Schema construct: 

<xsd: complexType name="Nanie"> 
<xsd: sequence> 
<xsd: element 

name=" item" 

type=" ImplementationType" 
minOccurs="0" 
maxOccurs="unbounded" /> 
</xsd: sequence> 
</xsd; complexType> 

B.4.1 .7 «TaggedChoiceOfDataElements» 

The UML TaggedChoiceOfDataElements data type contains the following attributes: 

• Name 

• SwitchType 

• Roles 

Name 
Type 

This type would then map to the following XML Schema construct: 

<xsd: complexType name="Name"> 
<xsd: sequence> 
<xsd: choice> 

<xsd: element name=" Role-Name" tYpe=" Role-Type" /> 
<xsd: element name=" Role-Name" tYpe=" Role-Type" /> 

<xsd: element nsime=" Role— Name" tYpe=" Role— Type" /> 

</xsd: choice> 
</xsd: sequence> 
</ complexType > 



B.5 Mapping of UML Interfaces to WSDL 

B.5.1 Mapping of UIVIL Operations to WSDL message element 

An UML Operation contains the following attributes: 
Interface 
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Operation Name 
Module Name 
Return Type 
Parameter 

Name 
Type 
This type would then map to the following WSDL message construct: 

<message name="Module_Name . Interf ace_Name . OperationName"> 
<part name="parameters" 

element ="xsdl :Module_Name . Interf ace_Name . OperationName" /> 
</message> 

<message name="Module_Name . Interf ace_Name . OperationNameResponse"> 
<part name="parameters" 

element ="xsdl :Module_Name . Interf ace_Name . Ope rat lonNameRe suit " /> 
</message> 

This approach is conformant with the wrapped document literal style recommended by the WS-I ( http://www.ws- 
i-org/) . 

B.5.2 Mapping of Exception to WSDL message element 

An UML Exception has the following attributes: 

• Module 

• Name 

This type would then map to the following XML Schema Construct: 

<message name="Module_Name . Exception_Name"> 
<part name="exception" 

element="xsdl : Module_Name . Exception_Name"/> 
</message> 

B.5.4 IVIapping of Interface Class to WSDL portType and binding 
elements 

A UML Interface contains the following attributes: 
Interface Name 
Module (i.e. component) 
Operations 

Name 

Parameters 

■ Name 

■ Exceptions 

■ Name 

This type would then map to the following WSDL portType element: 

<portType name="ModuleName . Interf aceName"> 
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<operation 

name=" Ope rat ion-Name" 

<input message="Operation-Name" /> 

<output message="Operation-NameResponse"/> 

<fault name=" Module .Operation-Exception-Name" 

message=" Module .Operation-Exception-Name" /> 
</operation> 
</portType> 

This type would also then map into the following WSDL binding element: 

<binding 

name= "Module. Inter face-NameSOAPBinding" 
type= "Module. Inter face-Name" > 

<soap : binding style=" document " transport="http : / /schema s . xmlsoap . org/soap/http" /> 

<operation name= "Operation-Name"> 

<soap : operation style="document" " /> 
<input> 

<soap:body use="literal"/> 
</ input > 
<output> 

<soap:body use="literal"/> 
</output> 
<f ault name="Module . Exception-Name> 

<soap: fault name="Module . Operation-Exception-Name" use="literal"/> 
</fault> 
... additional fault elements 
</operation> 

... additional operation elements 
</binding> 



B.5.5 Mapping of UML Interfaces to WSDL service element 

A UML Interface contains the following attributes: 
Interface Name 
Module 

This type would then map to the following WSDL service element: 

<service name=" Inter faceName"> 

<port binding= "Module. JnterfaceNameSOAPBinding" name=" Inter faceName"> 
<soap: address location="http .'//^Service Address}" /> 

</port> 

... additional port elements 
</service> 
</definitions> 
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Annex C (informative): 
Java™ Realisation API 

C.1 Java™ Realisation Overview 

The Parlay/OSA UML specifications are defined in a technology neutral manner. This annex aims to deliver for 
Java'"^, a developer API, provided as a realisation, supporting a Java'"^ API that represents the UML specifications. 

C.1.1 J2SE™API 

The J2SE'^ API supports a J2SE"^ development environment that 

• provides an abstraction of the Parlay/OSA APIs that provides a local API for J2SE'''m developers 

• supports a listener based API for SCFs and a callback API for the Framework 

• uses local object references as correlation mechanisms as Java"^ developers are familiar with object correlation 

• is a local API without visibility to the underlying transport 

C.1.2 J2EE™API 

The J2EE'^ API supports a development environment which allows the creation of J2EE'"^ and Java'^ RMI interfaces 
for both the server and client, ensuring consistent interfaces for interoperability. These interfaces may be used for 
Java''^ RMI on either JRMP or HOP (RMI/IIOP), allowing use in J2EE'''^ environments. The interfaces may also be 
used as a thin layer on other transports, similar to other Java^^ technologies that provide a RMI programming interface. 

The J2EE''^ API is a suitable base for Java''^ across Java'"*^ platforms, allowing creation of implementations that: 

• may be a thin layer on transport protocols 

• may support J2EE'''^ remote interfaces 

• may support J2EE'"'^ local interfaces 

The Java^^ files created with the realisation will be made available with the Parlay/OSA specifications. 
The remaining sections of this annex deal with the following areas: 

• section C.2 covers the tools and languages used to produce and define the Java'"^ Realisation 

• section C.3 covers the mappings that are common across both Java''^ Realisation APIs 

• section C.4 covers the mappings specific to the J2SE'''^ API 

• section C.5 covers the mappings specific to the J2EE"^ API 

C 1 .3 Javadoc™ 

The Javadoc''^ that accompanies the J2SEtm realisation of the Parlay/OSA API specification is provided as archive 
29I980IV640J2SE.ZIP that accompanies the present document. 

The Javadoc^"^ that accompanies the J2EE''''^ realisation of the Parlay/OSA API specification is provided as archive 
2919801V640J2EE.ZIP that accompanies the present document. 



£75/ 



3GPP TS 29.198-01 version 6.4.1 Release 6 32 ETSI TS 129 198-1 V6.4.1 (2006-07) 



C.2 Tools and languages 



The Java^'^ language is used as a means to programmatic ally define the interfaces. Java^'^ source files are generated 
automatically from UML. The Java''"^ source files are created in accordance with the mappings defined within this 
annex. 

The generated JavaT^ source files are verified syntactically using JavaT^ compilers such as javac. The JavaT"^ API 
comprises 

• J2SE''"'^ API designed to be compatible with the Java^M 2 SDK, Standard Edition, version 1.3 
( http://iava.sun.eom/i2se/l.3/) or later and a 

• J2EE''''^ API compatible with the Java'"^ 2 Enterprise Edition ( http://iava.sun.com/i2ee/). 

The J2SE''''^ API, developed in accordance to the conventions defined in section C.3 and C.4 will enable: 

• portable Javaf*^ applications, as far as the Javaf*^ API is concerned 

• independence of distribution mechanism technology (e.g. CORBA, SOAP, RMI) 

C.3 Generic mappings (Elements common to J2SE™ 
and J2EE™) 

NOTE: All Java'"^ code examples given in this section are taken from the J2SE''''^ Java'^^ Realisation API. See 
the appropriate Java'"^ files for examples for J2EE'"^ classes. 

C.3.1 Namespace 

The UML namespace org.csapi is represented by the Java^"^ package org.csapi.jr. 

Packages under the org.csapi.jr package will contain "se" packages for J2SE''''^ specific Java^"^ artefacts and "ee" and 
"eelocal" packages for J2EE''"^ specific JavaT'^ artefacts. 

For example, the User Location Camel Service package structure would appear as follows: 

org. csapi.jr.se. mm.ulc containing J2SE''''^ API Java^"^ artefacts 

org.csapi.jr.eelocal.mm.ulc contairring J2EE'''^ local API Java"""^ artefacts 

org.csapi.jr.ee.mm.ulc containing the J2EE''''^ remote/RMI API Java'^ artefacts 



C.3. 2 Package Naming Conventions 



UML packages will be represented by Java^^ packages. The sub-namespaces below the root namespaces described 
above will follow the naming used for the UML namespaces. 



C.3. 3 Object References 



In Javaf*^ there is no need to explicitly indicate a reference to an object as in Java'"^ objects are passed by value and not 
by reference. Where the specifications explicitly indicate a reference to an object by adding "Ref ' to the object type, 
this addition is removed in the Java''^ realisation. 

Example 1: 



UML 


Java™ Realisation 


IpUserLocationCamelRef 


UserLocationCamel 


IpCallRef 


Call 
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C.3.4 Element Naming 



The UML element names that begin with an uppercase will follow the Java''^ naming conventions of with a leading 
lower case letter and mixed case names. The UML elements are equivalent to Java'*^ field names. 

Example 2: 



UML 


Java™ Realisation 


Address PI an 


addressPlan 



C.3.5 Element Naming Collisions 



If an element name collides with a Java'*^ keyword, the element name will be prefixed with an underscore. 
Example 3: 



UML 


Java™ Realisation 


Final 


final 



C.3.6 Data Type Definitions 
C.3.6.1 Basic Data Types 

Java^*^ does not support type definitions (typedefs); therefore types are unwound to their basic data types e.i 
Example 4: 



UML 


Java™ Realisation 


TpCallAlertingMechanism 


int 


TpAccessType 


java.lang. String 



The following mappings apply to the basic data types: 



UML 


Java™ Realisation 


TpBoolean 


boolean 


Tplnt32 


int 


Tplnt64 


long 


TpFloat 


float 


TpOctet 


byte 


TpString 


java.lang. String 


TpLongString 


java.lang. String 


TpAny 


java.lang. Object 



C. 3.6.2 Constants 

Constants are associated with a type definition or as a standalone entity. In both cases, the constant itself will be defined 

as a 'public final static' field using its name and value. 

When defined associated with a type definition, an interface using the name of the type definition will be defined 
enclosing all constants associated with the type definition. 

Standalone constants within a package are defined within a Java'""^ interface with the name 'Constants' within that 
package. 

Example 5: 

package org.csapi.jr.se; 
public interface Constants { 
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public static final int METHOD_NOT_SUPPORTED = 22; 

public static final int NO_CALLBACK_ADDRESS_SET = 17; 

public static final int RE SOURCE S_UNAVAILABLE = 13; 

public static final int TASK_CANCELLED = 15; 

public static final int TASK_REFUSED = 14; 

public static final int INVALID_STATE = 744; 



Example 6: 

package org.csapi.jr.se.ee; 

public interface CallSuperviseReport { 

public static final int CALL_SUPERVISE_TIMEOUT = 1; 

public static final int CALL_SUPERVISE_CALL_ENDED = 2; 

public static final int CALL_SUPERVISE_TONE_APPLIED = 4; 



C.3.6.3 NumberedSetsOfDataElements (Collections) 

In JavaT"^, Numbered Set and Numbered List are realised as an array of the data type. 
Example 7: 



UML 


Java™ Realisation 


TpAddressSet 


Address[] 



C.3.6.4 SequenceOfDataElements (Structures) 

Struct data types are represented in Java'*^ as public final classes that implement java.io.Serializable, and have: 

• each data element made available as a private variable in the class 

• a default constructor and a constructor for all values are provided 

• accessor and mutator methods are given for each variable 

• the first letter of each sequence element name is changed to lower case 

• an equals method is provided detennining the equality of objects by their content 

• a hashCode method is provided supporting the rules for hashCode relative to equals 
Example 8: 

package org.csapi.jr.se; 

public final class Address implements java.io.Serializable { 

private AddressPlan plan; 

private String addrString = ""; 

private String name = ""; 

private AddressPresentation presentation; 

private AddressScreening screening; 

private String subAddressString = ""; 

public Address () { 



public Address (AddressPlan plan. String addrString, 

String name, AddressPresentation presentation, 
AddressScreening screening. String subAddressString) 

this. plan = plan; 

this . addrString = addrString; 

this. name = name; 

this .presentation = presentation; 

this . screening = screening; 

this . subAddressString = subAddressString; 
} 

public TpAddressPlan getPlan () { 
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return (plan) ; 



public void setPlan (TpAddressPlan plan) 
this. plan = plan; 



public String getAddrString () { 
return (addrString) ; 



public void setAddrString (String addrString) 
this . addrString = addrString; 



... other get and set methods ... 

public boolean equals (Object object) 
// equality logic 



public int hashcode () { 
// hash code calculation 



C.3.6.5 NameValuePair (Enumerations) 

NameValuePair data types are represented in Java'''^ as public final classes that implement java.io.Serializable, and 
have: 

• two static final data members per name-value pair 

• a value returning method, named getValue() 

• a name returning method, named getValueText() 

• an integer conversion method, named getObject() 

• a private constructor 

• readResolveO, hashCode and equals implementations 

No default constructor is provided. One of the data members per name-value pair has the same name as the name-value 
pair name. The other has an underscore "_" prepended and is intended for use in switch statements. Values are assigned 
sequentially, starting with 0. 

The getObjectO method returns the name-value pair class with the specified value if the specified value corresponds to 
an element of the name-value pair data type. If the specified value is out of range, an InvalidEnumValueException 
exception is raised. 

Example 9: 

package org.csapi.jr.se; 

public final class AddressScreening implements java.io.Serializable ( 

private int _value; 

private static int _size = 5; 

private static AddressScreening [ ] _array = new AddressScreening [_size] ; 

public static final int _ADDRESS_SCREENING_UNDEFINED = 0; 
public static final AddressScreening ADDRESS_SCREENING_UNDEFINED = new 
AddressScreening (_ADDRESS_SCREENING_UNDEFINED) ; 

public static final int _ADDRESS_SCREENING_USER_VERIFIED_PASSED = 1; 
public static final AddressScreening ADDRESS_SCREENING_USER_VERIFIED_PASSED = new 
AddressScreening (_ADDRESS_SCREENING_USER_VERIFIED_PASSED) ; 

public static final int _ADDRESS_SCREENING_USER_NOT_VERIFIED = 2; 
public static final AddressScreening ADDRESS_SCREENING_USER_NOT_VERIFIED = new 
AddressScreening (_ADDRESS„SCREENING_USER_NOT_VERIFIED) ; 
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public static final int _ADDRESS_SCREENING_USER_VERIFIED_FAILED = 3; 
public static final AddressScreening ADDRESS_SCREENING_USER_VERIFIED_FAILED = new 
AddressScreening (_ADDRESS_SCREENING_USER_VERIFIED_FAILED) ; 

public static final int _ADDRESS_SCREENING_NETWORK = 4; 
public static final AddressScreening ADDRESS_SCREENING_NETWORK = new 
AddressScreening („ADDRESS_SCREENING_NETWORK) ; 

private AddressScreening (int value) ( 

this._value = value; 

this ._array [this ._value] = this; 
1 

private Object readResolve ( ) throws Java. io .Ob jectStreamException { 

return _array [_value] ; 
} 

public int getValueO { 

return _value; 
} 

public String getValueText ( ) { 
switch (_value) { 
case _ADDRESS_SCREENING_UNDEFINED : 

return "ADDRESS_SCREENING_UNDEFINED" ; 
case _ADDRESS_SCREENING_USER_VERIFIED_PASSED : 

return "ADDRESS_SCREENING_USER_VERIFIED_PASSED" ; 
case _ADDRESS_SCREENING_USER_NOT_VERIFIED : 

return "ADDRESS_SCREENING_USER_NOT_VERIFIED" ; 
case „ADDRESS_SCREENING_USER_VERIFIED_FAILED : 

return "ADDRESS_SCREENING_USER_VERIFIED_FAILED" ; 
case _ADDRESS_SCREENING_NETWORK: 

return "ADDRESS_SCREENING_NETWORK" ; 
default : 

return "ERROR"; 



public static AddressScreening getObject (int value) throws 
org . csapi . jr.se. InvalidEnumValueException { 

if (value >= && value < _size) ( 

return _array [value] ; 
} else { 

throw new org . csapi . jr . se . InvalidEnumValueException () , 



public boolean equals (Object o) { 
//equality logic 



public int hashCode() { 
//hash code calculation 



C.3.6.6 TaggedChoiceOfDataElements (Unions) 

Union data types are represented in Java"^ as public final classes that implement java.io.Serializable, and have: 

• a default constructor 

• a discriminator field 

• a discriminator accessor method, named getDiscriminator() 

• an accessor and modifier method for each data element, the names of which are derived from choice element 
name 

• hashCode and equals implementations 
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Conflicting names should be resolved by prefixing the field name with an underscore for getDiscriminator if there is a 
name clash with the mapped data type name or any of the data element names. 

Where choice element type and choice element name are "NULL" and "Undefined", respectively, a Java^"^ Object set 
as null replaces the NULL. If multiple NULL/Undefmed combinations occur in the tagged choice of data elements, the 
method, setUndefined, will receive the discriminator as a parameter and set _object to null. 

Accessor methods shall raise an InvalidUnionAccessorException exception if the expected data element has not been 

set. 

Example 10: 

package org.csapi.jr.se; 

public final class AoCOrder implements Java. io . Serializable ( 

private CallAoCOrderCategory _cliscriminator = null; 

private Java . lang . Ob ject _object; 

public AoCOrder () { 
} 

public CallAoCOrderCategory getDiscriminator ( ) throws 
org . csapi . jr.se. InvalidUnionAccessorException ( 
if (^discriminator == null) ( 

throw new org . csapi . jr . se . InvalidUnionAccessorException () ; 
} 

return _discriminator; 
} 

public org . csapi . jr . se . ChargeAdvicelnfo getChargeAdviceInf o ( ) throws 
org . csapi . jr.se. InvalidUnionAccessorException ( 

if (_discriminator != CallAoCOrderCategory . CHARGE_ADVICE_INFO) { 

throw new org . csapi . jr . se . InvalidUnionAccessorException {) ; 
} 

return ( (org. csapi . jr. se . ChargeAdvicelnfo) _object); 
) 

public void setChargeAdvicelnfo (org. csapi . jr. se . ChargeAdvicelnfo value) ( 
„discriminator = CallAoCOrderCategory . CHARGE_ADVICE_INFO; 

^object = value; 
} 

public org . csapi . jr . se . ChargePerTime getChargePerTime ( ) throws 
org. csapi . jr.se. InvalidUnionAccessorException ( 

if (_discriminator != CallAoCOrderCategory . CHARGE_PER_TIME) { 

throw new org . csapi . jr . se . InvalidUnionAccessorException () ; 
} 

return ( (org . csapi . jr . se . ChargePerTime) _object); 
} 

public void setChargePerTime (org. csapi . jr. se . ChargePerTime value) ( 

_discriminator = CallAoCOrderCategory . CHARGE_PER_TIME; 

_object = value; 
} 

public Java . lang . String getNetworkCharge ( ) throws 
org . csapi . jr.se. InvalidUnionAccessorException ( 

if (.discriminator != CallAoCOrderCategory . CHARGE_NETWORK) { 

throw new org . csapi . jr . se . InvalidUnionAccessorException () ; 
} 

return (( Java. lang. String) _object); 
} 

public void setNetworkCharge ( Java. lang. String value) ( 

^discriminator = CallAoCOrderCategory . CHARGE_NETWORK; 

_object = value; 
} 

public void setUndefined (CallAoCOrderCategory discriminator) ( 

discriminator = discriminator; 

object = null; 

} 

public boolean equals (Object o) { 
//equality logic 
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public int hashCodeO { 
//hash code calculation 



C.3.6.7 Exceptions 

An exception maps to a constructed exception, providing appropriate constructors and accessor methods for the data 
contained within the exception. Each exception is defined as a pubHc class extending java.lang.Exception, and 
containing a private field for each information element contained within the exception. 

A default constructor is provided, along with a constructor containing only an embedded exception, a constructor 
containing a list of the fields in the exception and a constructor that contains the fields plus an embedded exception. 

An accessor method is provided for each field, and for the embedded exception. 

The following Java'*^ Realisations apply to mapping of exceptions: 

• PlatformException 

• P_XXX_XXX Exceptions 

• TpCommonExceptions 

• TpCommonExceptions' associated exceptions 

• Additional abstract exceptions 

• InvalidUnionAccessorException 

• InvalidEnumValueException 

C.3.6.7.1 PlatformException 

PlatformException exception handles local platform and communication problem exceptions. 
Example 11: 

package org.csapi.jr.se; 

public class PlatformException extends Java. lang.RuntimeException ( 
private Throwable _cause = null; 

public PlatformException () ( 
super ( ) ; 



public PlatformException (String message) { 
super (message) ; 



public PlatformException (String message, Throwable cause) 
super (message) ; 
„cause = cause; 



public PlatformException (Throwable cause) 
_cause = cause; 



public Throwable getCauseO { 
return _cause; 
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C.3.6.7.2 P_XXX_XXX Exceptions 

P_XXX_XXX exceptions follow the XxxXxxException naming pattern, and inherit from Java. lang.Exception. 
Example 12: 

package org.csapi.jr.se; 

public class InvalidlnterfaceTypeException extends Java. lang.Exception { 
private Throwable _cause = null; 

public Invalidlnterf aceTypeException ( ) ( 

super ( ) ; 
} 

public Invalidlnterf aceTypeException (String message) ( 

super (message) ; 
} 

public Invalidlnterf aceTypeException (String message, Throwable cause) ( 

super (message) ; 

_cause = cause; 
} 

public InvalidlnterfaceTypeException (Throwable cause) { 

_cause = cause; 
} 

public Throwable getCauseO { 
return _cause; 



C.3.6.7.3 TpCommonExceptions 

The name for TpCommonExceptions exception is made singular, i.e. CommonException, and inherits from 
Java. lang.Exception. 

Example 13: 

package org.csapi.jr.se; 

public class CommonException extends Java. lang.Exception ( 

private Throwable _cause = null; 

private int _exceptionType; 

private String _extralnf ormation; 

public CommonException () ( 

super ( ) ; 
} 

public CommonException (String message) ( 

super (message) ; 
} 
public CommonException (String message, Throwable cause) ( 

super (message) ; 

_cause = cause; 
} 

public CommonException (Throwable cause) ( 
_cause = cause; 



public Throwable getCauseO { 
return _cause; 



public int getExceptionType ( ) { 
return _exceptionType; 



public void setExceptionType (int exceptionType) ( 
_exceptionType = exceptionType; 
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public String getExtraInf ormation ( ) ( 
return __extra Information; 



public void setExtraInf ormation (String extrainf ormation) 
_extra Information = extrainf ormation; 



C. 3. 6. 7.4 TpCommon Exception's associated exceptions 

P_XXX_XXX exception types (constants) associated with TpCommonExceptions follow the XxxXxxException 
naming pattern and inherit from CommonException. 

Example 14: 

package org.csapi.jr.se; 

public class ResourcesUnavailableException extends org. csapi . jr. se . CommonException ( 
private Throwable _cause = null; 

public ResourcesUnavailableException () ( 

super ( ) ; 
} 

public ResourcesUnavailableException (String message) ( 

super (message) ; 
} 

public ResourcesUnavailableException (String message, Throwable cause) ( 

super (message, cause); 
} 

public ResourcesUnavailableException (Throwable cause) ( 
_cause = cause; 



C.3.6.7.5 Additional abstract exceptions 

Additional abstract exceptions (See ETSI ES 202 915-2, Annex D) have been defined which are 
TpInvalidArgumentException, TpFrameworkException, TpMobilityException, TpDataSessionException, 
TpMessagingException, TpConnectivityException, TpAccountException, TpPAMException and TpPolicyException 
and are mapped as follows: 

Example 15: 

package org.csapi.jr.se; 

public class InvalidArgumentException extends Java. lang. Exception ( 
private Throwable „cause = null; 

public InvalidArgumentException () ( 

super ( ) ; 
} 

public InvalidArgumentException (String message) ( 

super (message) ; 
} 

public InvalidArgumentException (String message, Throwable cause) ( 

super (message) ; 

_cause = cause; 
} 

public InvalidArgumentException (Throwable cause) ( 
_cause = cause; 
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public Throwable getCauseO { 
return _cause; 



C.3.6.7.6 InvalidUnionAccessorException 

An additional exception, InvalidUnionAccessorException, is defined which indicates that the expected data element has 
not been set. 

Example 16: 

package org.csapi.jr.se; 

public class InvalidUnionAccessorException extends org. csapi . jr . se . InvalidArgumentException ( 
private Throwable _cause = null; 

public InvalidUnionAccessorException (){ 

super ( ) ; 
} 

public InvalidUnionAccessorException (String message) ( 

super (message) ; 
} 

public InvalidUnionAccessorException (String message, Throwable cause) ( 

super (message, cause) ; 
} 

public InvalidUnionAccessorException (Throwable cause) ( 
_cause = cause; 



C.3.6.7.7 InvalidEnumValueException 

An additional exception, InvalidEnumValueException, is defined which indicates that an enum data type was accessed 
with an invalid request value. 

Example 17: 

package org.csapi.jr.se; 

public class InvalidEnumValueException extends org. csapi . jr. se . InvalidArgumentException ( 
private Throwable _cause = null; 

public InvalidEnumValueException () ( 

super ( ) ; 
} 

public InvalidEnumValueExceptions (String message) { 

super (message) ; 
} 

public InvalidEnumValueException (String message, Throwable cause) ( 

super (message, cause) ; 
} 

public InvalidEnumValueException (Throwable cause) { 
_cause = cause; 



C.3.6.8 Deprecation 

Java^*^ source can evolve between one version and the next. Three causes of evolution are identified: 
• Through applying changes to the UML 
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• Through applying changes to the rulebook 

• Through improving the Java''^ production process 

In order to maintain backward compatibility, the JavaT"^ community applies the /** ©deprecated */ tag. Java"^ source 
shall maintain backward compatibility. Changes between subsequent versions shall be indicated through applying the 
deprecated tag. 

Deprecated Javaf*^ source remains deprecated for as long as UML deprecation history is remained. 



C.4 J2SE™ Specific Conventions 

The UML interfaces are represented by Java'^ public interfaces; those interfaces that inherit from other interfaces are 
represented in Java^"^ as extending that interface. The Java^"^ realisations of OS A/Parlay SCFs use an Event Listener 
design pattern while the Framework uses the Callback pattern. 

This annex provides the information on realisation of the Java^^ developer API including: 

• How JavaT*^ APIs are realised from Parlay UML 

• Where the listener pattern is used, new classes to be generated from the UML 

• Changes required to data types and methods to support correlation using object references 

• Use of hierarchical exceptions 



C.4.1 Removal of "Tp" Prefix 



The UML data types labelled with the prefix "Tp" are represented in Java^*^ without this prefix. 
Example 18: 



UML 


Java™ Realisation 


TpCallApplnfo 


CallApplnfo 



In the case of name collisions between data types and interfaces as with IpTerminalCapabilities and IpService the UML 
data types labelled with the prefix "Tp" are represented in Java^"^ with an alternative prefix "Type". 

Example 19: 



UML 


Java™ Realisation 


IpTerminalCapabilities 


TerminalCapabilities 


TpTerminalCapabilities 


TypelerminalCapabilities 



The above example is based in conjunction with C.4. 3 Removal of "Ip" Prefix. 

C.4.2 Constants 

The UML constants labelled with the prefix "P_" are represented in Java^*^ without this prefix. 
Example 20: 



UML Constant 


Java™ Constant 


P NO CALLBACK ADDRESS SET 


NO CALLBACK ADDRESS SET 
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C.4.3 Removal of "Ip" prefix 

The "Ip" prefix is removed in the Java'''^ realisation of UML interfaces. 
Example 2 1 : 



UML 


Java™ 


IpCallControlManager 


CallControlManager 



C.4.4 Mapping of Iplnterface 



Iplnterface interface is represented by the Csapilnterface interface. This is a 'marker' interface, in that it contains no 
methods, but provides a common interface for related interfaces to inherit from. All interfaces to be serializable; this 
can be done by Csapilnterface extending Serializable. 

Example 22: 

package org.csapi.jr.se; 

public interface Csapilnterface extends Serializable! 



C.4.5 IVIapping of IpService 



IpService interface is represented by the Java'^ Service interface. This provides a common interface for related 
interfaces to inherit from. 

Example 23: 

Service Interface: 

package org.csapi.jr.se; 

public interface Service extends Csapilnterface ( 

public final static int IN_SERVICE_STATE=0 ; 

public final static int 0UT_0F_SERVICE_STATE=1; 

void addServiceStateChangeListener (ServiceStateChangeListener listener) 

int getServiceState ( ) ; 

void removeServiceStateChangeListener ( ServiceStateChangeListener listener) ; 



Listener interface: 

package org.csapi.jr.se; 

public interface ServiceStateChangeListener extends Java . util . EventListener ( 
void onOutOf Service (OutOfServiceEvent event); 



Event class: 

package org.csapi.jr.se; 

public class OutOfServiceEvent extends jav.util .EventOb ject { 

public OutOf ServiceEvent ( Java. lang. Ob ject source)! 
super (source) 

} 
} 



C.4.6 IVIapping of UML Operations 

The UML operations are represented in Java^"^ as methods. 
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Exceptions that can be raised by UML operations are represented in JavaT'^ with the throws clause and the JavaT"^ 
ReaHsation of the UML Exceptions. 

UML "in" parameters, represented by "in " preceding the parameter type are represented in Java^^ without this clause. 

Example 24: 

public void managerResumed (); 

public Csapilnterface obtainlnterface (InterfaceName interfaceName) throws 
InvalidlnterfaceNameException; 

public Service createServiceManager (ClientAppID application^ ServicePropertyList serviceProperties, 
ServicelnstancelD servicelnstancelD) ; 

The above example method signatures are based on generic mapping of interfaces, exceptions and data types. 



C.4.7 Mapping of TpSessionID 



The UML TpSessionID data types will be hidden in the J2SE''"'^ APIs (and optionally supported by the underlying 
Java'"^ implementation). Consequently, the TpSessionlDSet data type and IpService.setCallbackWithSessionID() 
method are superfluous. Also, structures with only TpSessionID and interface references (e.g. TpCallldentifier) are no 
longer necessary and references to these structures should be replaced by just the reference to the interface. For data 
types that contain TpSessionID the Java'"^ API Realisation object replaces theTpSessionlD. 

The following figure shows how Java'^ API Realisation objects relate to Parlay UML objects and sessions. How this is 
realised in the adaptors is implementation dependent. 



Java API Realisation Objects 



Parlay UML Object 




Parlay UML Sessions 



C.4.8 Mapping of TpAssignmentID to the creation of an Activity 
object 

The UML TpAssignmentID data types, which differentiate between multiple parallel asynchronous method invocations 
(activities) on the same ("parent") interface, are deleted and replaced with createXxx methods (one for each parallel 
asynchronous activity) that create ("child") activity interfaces. Where this would result in method names of the pattern 
createCreateXxx, this should be changed to method names with the pattern createXxx. Associated listeners would then 
remove the Create prefix from their name. These activity interfaces, in addition to possibly supporting other methods, 
will support one of the previously mentioned multiple parallel asynchronous method invocations. Hence, the Java'''^ 
API realisation creates multiple (activity) objects and invokes a single request per object rather than creating a single 
object and invoking multiple requests on that object, each request being differentiated using the TpAssignmentID value. 
The results of the asynchronous method invocation will be handled by the activity interface's listener interface. To 
create the activity interface, the original IpXxx interface (to be named Xxx) will replace its parallel supporting 
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asynchronous method invocations, yyyYyyReq, with create YyyYyy methods that take no parameters but returns the 
activity interface, YyyYyy. Where this would result in method names of the pattern createCreateXxx, this should be 
changed to method names with the pattern createXxx. Associated listeners would then remove the Create prefix from 
their name. The activity interface will extend Activity interface (see next rule), have a simple FSM, the 
addYyyYyyListener, remove YyyYyyListener and the asynchronous method that previously supported a parallel 
capability (typically named yyyYyyReq, but also yyyYyyStop). 

An Activity interface, packaged in org.csapi.jr.se, is added as a parent to all activity interfaces. An application may add 
listeners of type ActivityStateChangeListener to an Activity if it wishes be explicitly informed when the activity 
becomes invalid. 

The YyyYyyListener activity listener interfaces will extend java.util.EventListener. The asynchronous methods of 
previously named IpAppXxx, typically labelled yyyYyyRes and yyyYyyErr but also yyyYyy, will be renamed 
onYyyYyyRes and onYyyYyyErr but also on YyyYyy. Each method will have an event parameter, typically labelled 
YyyYyyResEvent and YyyYyyErrEvent, but also YyyYyyEvent. Events will be classes that extend 
java.util.EventObject and contain a public constructor (with multiple parameters - one per class carried by the event) 
and a number of public getter methods (one per "gettable" class carried by the event). As a result of adding activity 
listener interfaces, this may cause the requirement for the original IpAppXxx to disappear, since the yyyYyyRes and 
yyyYyyErr methods will effectively be ported to the activity listener interfaces. 

For data types that contain TpAssignmentID the activity object replaces the TpAssignmentlD. 

Example 25: 

Activity Interface: 

package org.csapi.jr.se; 

public interface Activity extends Csapilnterface ( 

public final static int IDLE_STATE = 0; 

public final static int ACTIVE_STATE = 1; 

public final static int INVALID_STATE = 2; 

public int getStateO; 

public void addActivityStateChangeListener (ActivityStateChangeListener listener) ; 

public void removeActivityStateChageListener (ActivityStateChangeListener listener) ; 



Activity Listener Interface and Event class: 

package org.csapi.jr.se; 

public interface ActivityStateChangeListener { 

onlnvalidStateEvent (InvalidActivityEvent event) 



public class InvalidActivityEvent extends java.util.EventObject { 
public InvalidActivityEvent ( Java. lang. Ob ject source)! 
super (source) 



Parent interface: 

package org. csapi . jr . se .mmm.ul; 

public interface UserLocation extends org. csapi . jr. se . Service ( 

public LocationReport createLocationReport ( ) ; 

public ExtendedLocationReport createExtendedLocationReport ( ) ; 

public PeriodicLocationReporting createPeriodicLocationReporting ( ) 



Child Interface: 

package org. csapi . jr . se .mm.ul; 

public interface LocationReport extends org. csapi . jr. se .Activity { 

public void addLocationReportListener (LocationReportListener listener) 
public void removeLocationReportListener (LocationReportListener listener) 
public void locationReportReq (Address [ ] users) throws ... 
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Listener Interface: 

package org. csapi . jr . se .mm.ul; 

public interface LocationReportListener extends Java . util . EventListener ( 

public void onLocationReportResEvent (LocationReportResEvent event) 
public void onLocationReportErrEvent (LocationReportErrEvent event) 



Event classes: 

package org. csapi . jr. se .mmm.ul; 

public class LocationReportResEvent extends Java. util .EventObject ( 

// with a public UserLocation [ ] constructor and a public getter 

// method for the parameter of the event 
} 

public classLocationReportErrEvent extends Java . util . EventObject ( 

// with a public MobilityError and MobilityDiagnostic constructor 
// and two public getter methods, one for each of the parameters 
// of the event 

} 



The Finite State Model for the Activity interface is given below: 



\^ 



Idle 



Active 



Invalid 



^ 





This interface specifies an activity, which might be provided by a service. An activity has three states: "idle", "active" 
and "invalid". The initial state is "idle" and here the listeners should be registered. It performs in the "active" state. It 
enters the "invalid" state when it has fulfilled its task or a fatal error occurred. In special cases state transition from 
"idle" to "invalid" is possible. 

An example activity interface FSM is given below for a single activity request with a single response: 
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locationReportReqO exception 



V 



Idle 




addLocationReportListenerO 
removeLocationReportListenerO 



Active 



locationReportReqO 

removeLocationReportListenerO 




'^LocationReportResEvent 
'^LocationReportErrEvent 



Invalid 



® 



An example activity interface FSM is given below for a single activity request with repeating responses: 



V 



periodicLocationReportingStartReqO except ion 



Idle 




addPeriodicLocationReportingListenerO 
removePeriodicLocationReportingListenerO 



periodocLocationReportingStartReqO 



Active 




removePeriodicLocationReportingListenerO 
'^PeriodicLocationReportEvent 
periodicLocationReportingStopC'selected users") 



periodicLocationReportingStopC'all users") 
'^PeriodicLocationReportErrEvent 



Invalid 



^ 



C.4.9 Callback Rule 

The UML callback design pattern for all callbacks that return a type is represented in Java'*^ with the callback design 
pattern. The UML callback design pattern for all callbacks that return void is represented in Java"^ with the event 
listener design pattern. 

The UML client-to-service interfaces with the IpAppXxxx naming convention are represented in JavaT'^ with the 
XxxxListener naming convention. 
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The IpService.setCallback method can be deleted; the interfaces that inherited the setCallback method now have 
associated addXxxxListener and removeXxxxListener methods. According to the TpSessionID mapping, 
IpService.setCallbackWithSessionlDO method is deleted. 

The XxxxListener listener interfaces will extend java.util.EventListener. The asynchronous methods of previously 
named IpAppXxxx, typically labelled yyyyYyyyRes and yyyyYyyyyErr but also yyyyYyyy, will be renamed 
onYyyyYyyyRes and onYyyyYyyyErr but also onYyyyYyyy. Each method will have an event parameter, typically 
labelled Yyyy YyyyResEvent and YyyyYyyyErrEvent, but also YyyyYyyyEvent. Events will be classes that extend 
java.util.EventObject and contain a private constructor (with multiple parameters - one per class carried by the event) 
and a number of public getter methods (one per "gettable" class carried by the event). Events are read-only and 
serializable. 

Example 26: 

Listener Interface: 

package org. csapi . jr . se . cc .mpccs; 

MultiPartyCallListener extends java.util.EventListener! 

public void onGetlnfoResEvent (GetlnfoResEvent event) 

public void onGetlnfoErrEvent (GetlnfoErrEvent event) 

public void onSuperviseResEvent (SuperviseResEvent event) 

public void onSuperviseErrEvent (SuperviseErrEvent event) 

public void onCallEndedEvent (CallEndedEvent event) 

public void onCreateAndRouteCallLegErrEvent (CreateAndRouteCallLegErrEvent event) 



MultiPartyCall Interface additional methods: 

public void addMultiPartyCallListener (MultiPartyCallListener multiPartyCallListener) ; 
public void removeMultiPartyCallListener (MultiPartyCallListener multiPartyCallListener) 



C.4.10 Factory Rule 



The following Factory class allows applications to obtain proprietary peer API objects. The term "peer" is Java'^^ 
nomenclature for a particular platform-specific implementation of a Java'^^ interface. 

Example 27: 

package org. csapi . jr . se . fw; 

import org . csapi . jr.se. PeerUnavailableException; 
import org . csapi . jr.se. I nvalidArgument Except ion; 
import org . csapi . jr.se. ResourcesUnavailableException; 
import org . csapi . jr.se. f w. access . tsm. Initial; 
import Java . util . *; 

public class InitialFactory ( 

private static InitialFactory myFactory; 
private static String className = null; 
private static String lang = "en"; 
private static String entry = "US"; 

private InitialFactory ( ) ( 
} 

public synchronized Initial createlnitial (String initialPeerRef erence) throws 
PeerUnavailableException, ResourcesUnavailableException, I nvalidArgument Except ion ( 
Locale current Locale; 
ResourceBundle messages; 
String tryMessage; 

try ( 

currentLocale = new Locale (lang, entry); 

messages = ResourceBundle . getBundle ( "InitialFactoryBundle", currentLocale) ; 

// Validate all used values before using them later 

// avoiding error text exception to hide the real exception 

tryMessage = messages . get St ring ( " InitialPeerRef erenceNull" ) ; 
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tryMessage = messages . getstring ( "InitiallnstFailure" ) ; 

tryMessage = message . getString ( "DestroylnitialFailure" ) ; 
} 
catch (Exception e) { 

throw new ResourcesUnavailableException ("Localisation failed to be initialized"); 
} 

if (initialPeerRef erence == null) ( 

String errmsg = messages . getString (" InitialPeerRef erenceNull" ) ; 

throw new InvalidArgumentException (errmsg) ; 
} 

try { 

Class c = Class . forName (getlmplementationClassName ()); 
if (initialPeerRef erence . equals ("" ) ) ( 

// Creates a new instance of the Object class 

// using default constructor 

return ( Initial) c . newlnstance (); 
) 

Class [] paramTypes = { initialPeerRef erence . getClass ()} ; 
Java. lang. reflect . Constructor ctor = 
c . get Construct or (paramTypes) ; 
Object [] params = ( initialPeerReference} ; 
return (Initial) ctor . newlnstance (params ) ; 
} catch (Exception e) { 

String errmsg = messages . getString (" InitiallnstFailure" ) ; 
throw new PeerUnavailableException (errmsg) ; 



public synchronized static InitialFactory getlnstance ( ) { 

if (myFactory == null) { 

myFactory = new InitialFactory (); 

} 

return myFactory; 
) 

public String getlmplementationClassName () ( 
return className; 



public static void setlmplementationClassName (String className) ( 
this . ClassName = className; 



public synchronized static void setLocale (String language. String country) 
if (language == null) { 

lang = "en"; 
} 
else { 

lang = language; 



if (country == null) { 
entry = "US"; 

} 

else { 

entry = country; 



public void destroylnitial (Initial initiallnstance) ( 
if (initiallnstance == null) ( 
return; 



try { 

delete initiallnstance; 
} catch (Exception e) { 

String errmsg = messages . getString ( "DestroylnitialFailure" 

throw new RuntimeException (errmsg) ; 
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C.4.1 1 J2SE™ Specific Exceptions 

Exceptions in this section are only applicable within a J2SE''''^ environment. 

C.4.11 .1 PeerUnavailableException 

PeerUnavailableException indicates failure to access an implementation of the Initial interface. 
Example 28: 

public class PeerUnavailableException extends Java. lang. Exception ( 
private Throwable _cause = null; 
public PeerUnavailableException () { 

super ( ) ; 
} 

public PeerUnavailableException (String message) ( 

super (message) ; 
} 

public PeerUnavailableException (String message, Throwable cause) ( 

super (message) ; 

_cause = cause; 
} 

public PeerUnavailableException (Throwable cause) ( 

_cause = cause; 
} 

public Throwable getCauseO { 
return _cause; 



C.4.11 .2 lllegalStateException 

Illegals tateException exception signals that a method has been invoked at an illegal or inappropriate time. 
Example 29: 

package org.csapi.jr.se; 

public class lllegalStateException extends Java. lang. Exception ( 

private int _state; 

private Java . lang . Ob ject _object; 

public lllegalStateException (Ob ject object, int state) ( 
super ( ) ; 
_object = object; 

_state = state; 
} 

public Illegal StateException (Ob ject object, int state. String s) ( 
super (s) ; 
_object = object; 

_state = state; 
} 

public Object getObjectO { 

return _object; 
} 

public int getState() ( 
return _state; 
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C.4.12 User Interaction Specific Rules 

C.4.12.1 Interfaces representing UML IpUl and IpUICall Rule 

The following mappings take account of the fact that when the TpAssignmentID rule is applied the Java'^ interfaces 
representing UML IpUICall does not extend the Java^'^ interfaces representing UML IpUI. 

JavaT"^ UIGeneric replaces the UML IpUI. Methods common to both the Java'"'^ UIGeneric and Java^^ UlCall are 
pulled up into a super-interface called UI. UML IpAppUI and IpAppUiCall interfaces are replaced by a UIListener 
interface. 

C.4.12.2 Naming Collisions of IpUI and IpUICall Rule 

Naming collisions that arise through IpUI and IpUICall methods e.g. XXX, having the same name will be dealt with by 
prefixing the Call Related UI activities by "CallRelated". Methods to create the activity will become 
createCallRelatedXXXO and events will become CallRelatedXXXEvent. 

C.4.12.3 Naming Collisions of IpUICall and IpUIAdminManager Rule 

Naming collisions that arise through IpUICall and IpUIAdminManager methods,e.g. XXX, having the same name will 
be dealt with by prefixing the UI Admin activities by "AdminRelated". Methods to create the activity will become 
createAdminRelatedXXXO and events will become AdminRelatedXXXEvent. 

C.5 J2EE™ Specific Conventions 

J2EET'^ supports both remote and local interfaces. 

C.5.1 Void 

C.5. 2 Remote Interface Definitions 
C. 5.2.1 Iplnterface 

This interface implements java.io.Serializable. Since it is the root interface for all other interfaces, this makes all 
defined interfaces serializable. 

Example 30: 

public interface Iplnterface extends java.io.Serializable 



C.5. 2. 2 Methods for Remote Interfaces 

A public method is defined within a remote interface for each method defined in the specification, with zero or one 
output specified as the return value, and all other parameters listed without any input marker. Each method will return 
java.rmi.RemoteException in addition to other exceptions, if any. 

Example 3 1 : 

public void deassignCall (int callSessionID) throws java.rmi.RemoteException, 
org . csapi . jr.ee. TpCommonException, org . csapi . jr.ee. InvalidSessionldException; 
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C.5.3 Local Interface Definitions 
C.5.3.1 Methods for Local Interfaces 

A public method is defined within a local interface for each method defined in the specification, with zero or one output 
specified as the return value, and all other parameters listed without any input marker. 

Example 32: 

public void deassignCall (int callSessionID) throws org. csapi . jr . ee . TpCommonExceptions, 
org . csapi . jr.ee. InvalidSessionldException; 



C.5.4 Multi Party Call Control Specific Rules 

The Multi Party Call Control Manager interface has specific Java''^ Realisation considerations. 

0.5.4.1 IpCallLeg and IpAppCallLeg method name conflicts 

Some method names within the IpAppCallLeg interface have the same names as methods in the IpAppMultiPartyCall 
interface. These method names conflict when both interfaces are implemented on the same object within an RMI/IIOP 
or CORBA environment. 

For the method names that are the same in both IpMultiPartyCall and IpCallLeg interfaces or IpAppMultiPartyCall and 
IpAppCallLeg, the call leg related method names are modified to include "CallLeg" as part of the method name to 
avoid name conflicts. The following method names result: 



IpCallLeg Method Name 


Realisation Method Name 


getlnfoReq 


getCallLeglnfoReq 


superviseReq 


superviseCallLegReq 



Table 1 : IpCallLeg method name modifications 



IpAppCallLeg Method Name 


Realisation Method Name 


getlnfoRes 


getCallLeglnfoRes 


getlnfoErr 


getCallLeglnfoErr 


superviseRes 


superviseCallLegRes 


superviseErr 


superviseCallLegErr 



Table 2: IpAppCallLeg method name modifications 
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Annex D (informative): 

Description of Overview for 3GPP2 cdma2000 networks 

This annex is intended to define the OSA API Stage 3 interface definitions and it provides the complete OSA 
specifications. It is an extension of OSA API specifications capabilities to enable operation in cdma2000 systems 
environment. They are in alignment with 3GPP2 Stage 1 requirements and Stage 2 architecture defined in: 

[1] 3GPP2 P.SOOOl-B: "Wireless IP Network Standard", Version 1.0, September 2000. 

[2] 3GPP2 S.R0037-0: "IP Network Architecture Model for cdma2000 Spread Spectrum Systems", 

Version 2.0, May 14, 2002. 

[3] 3GPP2 X.S0013: "All-IP Core Network Multimedia Domain", December 2003. 

These requirements are expressed as additions to and/or exclusions from the 3GPP Release 6 specification. 

The information given here is to be used by developers in 3GPP2 cdma2000 network architecture to interpret the 3GPP 

OSA specifications. 



D.1 General Exceptions 



The terms 3GPP and UMTS are not applicable for the cdma2000 family of standards. Nevertheless these terms are used 
(3GPP TR 21.905 [1]) mostly in the broader sense of "3G Wireless System". If not stated otherwise there are no 
additions or exclusions required. 

CAMEL and CAP mappings are not applicable for cdma2000 systems. 



D.2 Specific Exceptions 
D.2.1 Clause 1: Scope 

There are no additions or exclusions. 

D2.2 Clause 2: References 

Normative references on 3GPP TS 23.078 and on 3GPP TS 29.078 [8] are not applicable for cdma2000 systems. 

D2.3 Clause 3: Definitions and abbreviations 

There are no additions or exclusions. 

D2.4 Clause 4: Open Service Access APIs 

There are no additions or exclusions. 

D2.5 Clause 5: Structure of the OSA API (29.198) and Mapping 
(29.998) documents 

There are no additions or exclusions. 
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D.2.6 Clause 6: Methodology 

There are no additions or exclusions. 

D.2.7 Clause 7: Introduction to OSA APIs 

There are no additions or exclusions. 

D.2.8 Annex A (normative): OMG IDL 

There are no additions or exclusions. 

D.2.9 Annex B (informative): W3C WSDL 

There are no additions or exclusions. 

D.2.10 Annex C (informative): Java™ API 

There are no additions or exclusions. 
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Annex E (informative): 
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